home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Development Platforms / Apple II / Essentials / Technical.Notes / IIGS / TN.IIGS.046 < prev    next >
Encoding:
Text File  |  1989-01-09  |  10.6 KB  |  200 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6.  
  7. Apple IIGS
  8. #46:    DrawPicture Data Format
  9.  
  10. Written by:    Jeff Erickson & Keith Rollin                     November 1988
  11.  
  12. This Technical Note describes the internal format of the QuickDraw II picture 
  13. data structure.
  14. _____________________________________________________________________________
  15.  
  16. This Technical Note presents the internal format of the QuickDraw II picture 
  17. data structure for informational purposes only.  You should not use this 
  18. information to write your own bottleneck procedures; the only routines which 
  19. should create and read PICT format files are those provided in QuickDraw II.  
  20. If we added new objects to the picture definition, your program would not 
  21. operate on new pictures.  This Note documents this information for debugging 
  22. purposes only.
  23.  
  24.  
  25. Picture Data Structure Definition
  26.  
  27. Pictures are stored in memory in the following format:
  28.  
  29. They begin with a WORD which indicates the mode of the port which was used to 
  30. record when the picture was created.  This information is useful when the 
  31. picture is played back, possibly in a different graphics mode.
  32.  
  33. Following the WORD is a RECT which indicates the frame of the picture and is 
  34. used for scaling when you redraw the picture.  Following the RECT is the 
  35. version number of this PICT format, then a series of word-sized opcodes which 
  36. describe the sequences of QuickDraw II commands that were used to create the 
  37. picture.
  38.  
  39. Name        Description                         Size (bytes)
  40. pictSCB     picture's scan line control byte    2 (high byte = 0)
  41. picFrame    picture's boundary rectangle        8
  42. version     picture version                     2 (Currently $8211)
  43. opcode      operation code                      2
  44. <data>      operation data                      variable, depending on opcode
  45. :
  46. opcode      operation code                      2
  47. <data>      operation data                      variable, depending on opcode
  48.  
  49.  
  50. Opcodes
  51.  
  52. As mentioned above, pictures are described by a series of opcodes which are 
  53. used to record the QuickDraw II commands that created the picture.  These 
  54. opcodes are two bytes long and are usually followed by a number of parameters.
  55.  
  56. All currently defined opcodes and their parameters are listed below.  Any 
  57. opcodes not listed here are reserved.
  58.  
  59. Opcode Name          Description         Parm Bytes    Parameter Description
  60. $0000  NOP           no operation        0             none
  61. $0001  ClipRgn       clip to a region    [region size] region
  62. $0002  BkPat         background pattern  32            background pattern (8x8 
  63.                                                        pixels)
  64. $0003  TxFont        text font           4             Font Manager font ID
  65.                                                        (long)
  66. $0004  TxFace        text face           2             text face (word)
  67. $0005  TxMode        text mode           2             text mode (word)
  68. $0006  SpExtra       space extra         4             space extra (fixed)
  69. $0007  PnSize        pen size            4             pen size (point)
  70. $0008  PnMode        pen mode            2             pen mode (word)
  71. $0009  PnPat         pen pattern         32            pen pattern (8x8 pixels)
  72. $000A  FillPat       fill pattern        32            fill pattern (8x8
  73.                                                        pixels)
  74. $000B  OvSize        oval size           4             oval size (point)
  75. $000C  Origin        origin              4             origin (point)
  76. $000D  TxSize        text size           2             text size (word)
  77. $000E  FGColor       foreground color    2             color (word)
  78. $000F  BGColor       background color    2             color (word)
  79. $XX11  Version       version             0             none: high byte=version 
  80.                                                        (currently $82)
  81. $0012  ChExtra       character extra     4             char. extra (fixed)
  82. $0013  PnMask        pen mask            8             mask (8 bytes)
  83. $0014  ArcRot        arc rot             2             Reserved (related to
  84.                                                        things drawn with
  85.                                                        patterns). (word)
  86. $0015  FontFlags     font flags          2             font flags (word)
  87. $0020  Line          line                8             pnLoc (point), newPt
  88.                                                        (point)
  89. $0021  LineFrom      line from pen loc.  4             newPt (point)
  90. $0022  ShortLine     short line          6             pnLoc (point), dv, dh 
  91.                                                        (signed bytes)
  92. $0023  ShortLFrom    ditto from pen loc  2             dv, dh (signed bytes)
  93. $0028  LongText      long text           5+text        txLoc (point), count
  94.                                                        (byte), text
  95. $0029  DHText        hor. offset text    2+text        dh (unsigned byte),
  96.                                                        count (byte), text
  97. $002A  DVText        vert. offset text   2+text        dv (unsigned byte),
  98.                                                        count (byte), text
  99. $002B  DHDVText      offset text         3+text        dv, dh (unsigned bytes), 
  100.                                                        count (byte), text
  101. $002C  RealLongText  very long text      6+text        txLoc (point), count
  102.                                                        (word), text
  103.  
  104. Opcodes between $0030 and $008C are a combination of a graphic verb and a 
  105. graphic object, as listed below (where "V" stands for the graphic verb, and 
  106. "X" is a stands for the graphic object).  For example, $0069 means 
  107. PaintSameArc, and is followed by two one-word parameters.
  108.  
  109. Graphic Verbs:
  110.  
  111. $00X0      Frame...      frame something            [Specific to object type
  112.                                                     see below.]
  113. $00X1      Paint...      paint something
  114. $00X2      Erase...      erase something
  115. $00X3      Invert...     invert something
  116. $00X4      Fill...       fill something
  117. $00XV+8    ...Same...    draw same thing somehow    [See below; {braced}
  118.                                                     parms do not appear.]
  119.  
  120. Graphic Objects:
  121.  
  122. $003V      ...Rect       draw a rectangle somehow   8 (0 if - SameRect) {rect
  123.                                                     (2 points)}
  124. $004V      ...RRect      draw a round rect somehow  8 (0) {rect (2 points)}
  125. $005V      ...Oval       draw an oval somehow       8 (0) {rect (2 points)}
  126. $006V      ...Arc        draw an arc somehow        12 (4) {rect (2 points)},
  127.                                                     start, arc angle (words)
  128. $007V      ...Poly       draw a polygon somehow     [polygon size] (0){polygon}
  129. $008V      ...Rgn        draw a region somehow      [region size] (0) {region}
  130. $0090      BitsRect      copybits, rect clipped     variable* (see below, but
  131.                                                     without maskRgn)
  132. $0091      BitsRgn       copybits, rgn clipped      variable* (see below)
  133. $00A1      LongComment   long comment               4+data kind (word), size
  134.                                                     (word), data
  135.  
  136. *Bits... data:
  137.  
  138. origSCB       original scan line control byte  2               SCB (word --
  139.                                                                high byte = 0)
  140. BWvsColor     black and white vs. color        2               reserved (word)
  141. width         width of pixel image in bytes    2               width (word)
  142. boundsRect    bounds rectangle                 8               rect (2 points)
  143. srcRect       source rectangle                 8               rect (2 points)
  144. destRect      destination rectangle            8               rect (2 points)
  145. mode          transfer mode                    2               pen mode (word)
  146. maskRgn       mask region (BitsRgn ONLY!)      [region size]   region
  147. pixData       pixel image                      [pixdata size]  width*
  148.                                                                (bounds.bottom-
  149.                                                                bounds.top)
  150.  
  151.  
  152. Differences Between IIGS Pictures and Macintosh Pictures
  153.  
  154. 1.    QuickDraw II pictures are modeled after PICT2 on the Macintosh, 
  155.       which use two bytes for its opcodes and data (the exception to 
  156.       this is the $11 (version) opcode, which is followed by a one-byte 
  157.       parameter).  Macintosh PICT 1.0 formats, which use one-byte 
  158.       opcodes, would have to undergo extensive modifications to be 
  159.       displayed on the IIGS.
  160. 2.    There is no EndOfPicture opcode on the IIGS as there is on the 
  161.       Macintosh.  Also, the first word of the picture is a pictSCB, not 
  162.       the length of the picture.  The picture size is determined solely 
  163.       by the size of the handle on the IIGS.  There is also no picture 
  164.       header on the IIGS as on the Macintosh.
  165. 3.    The number sex of the Macintosh is opposite that of the Apple 
  166.       IIGS. The Macintosh stores the high bytes of words and long words 
  167.       first, whereas the IIGS stores the low byte first. 
  168. 4.    The following Macintosh picture opcodes are not available on the 
  169.       IIGS: txRatio, PackBitsRect, PackBitsRgn, shortComment, 
  170.       EndOfPicture.
  171. 5.    QuickDraw II defines the following opcodes that the Macintosh does 
  172.       not: ChExtra ($12), PnMask ($13), ArcRot ($14), FontFlags ($15), 
  173.       and RealLongText ($2C).
  174.  
  175.  
  176. Notes on the Interpretation of IIGS Pictures
  177.  
  178. o    The state of the pen, the clip region, various patterns and 
  179.      colors, and the origin of the current port is saved before a 
  180.      picture is drawn, and restored afterwards.  The current port is 
  181.      set up in a default state equivalent to that of a newly created 
  182.      port just before drawing begins.  Picture opcodes act just like 
  183.      their QuickDraw II tool counterparts, with a few exceptions.
  184. o    Two pen locations are tracked as the picture is drawn, one for 
  185.      lines and one for text.  Thus, LineFrom always draws from the end 
  186.      of the last line, regardless of any intermediate text opcodes.
  187. o    Text calls do not change the position of the "text pen," as do 
  188.      normal QuickDraw II text calls.  Thus, if a picture contains two 
  189.      lines of text, the second one directly below the first, the second 
  190.      will be stored using a DVtext opcode.
  191. o    DrawPicture performs considerable setup before it draws pictures.  
  192.      Among other things, it calls InstallFont, which is a Font Manager 
  193.      call.  If you are going to support pictures in your application, 
  194.      you should load and start the Font Manager. 
  195.  
  196.  
  197. Further Reference
  198. o    Apple IIGS Toolbox Reference, Volume 2
  199.  
  200.